'\" te
.\" Copyright (c) 1986-2006 AT&T Knowledge Ventures
.\" To view license terms, see http://www.opensource.org/licenses/cpl1.0.txt
.\" Portions Copyright (c) 2007, Sun Microsystems, Inc.
.TH msgcpp 1 "9 Oct 2007" "SunOS 5.11" "User Commands"
.SH NAME
msgcpp \- C language message catalog preprocessor
.SH SYNOPSIS
.LP
.nf
\fBmsgcpp\fR [\fB-ACEHMPVX\fR] [\fB-D\fR \fIname\fR[\fB=\fR\fIvalue\fR]] [\fB-I\fR \fIdirectory\fR] [\fB-U\fR \fIname\fR] 
 [\fB-T\fR[\fIlength\fR]] [\fB-Y\fR \fIdirectory\fR] [\fIinput\fR [\fIoutput\fR] ]
.fi

.SH DESCRIPTION
.sp
.LP
\fBmsgcpp\fR is a C language message catalog preprocessor. It accepts \fBcpp\fR(1) style options and arguments. \fBmsgcpp\fR preprocesses an input C source file and emits keyed lines to the output, usually for further processing by\fBmsgcc\fR(1). \fBmsgcc\fR output is in the \fBgencat\fR(1) syntax. Candidate message text is determined by arguments to the last \fB<error.h>\fR and \fB<option.h>\fR functions. The \fBmsgcpp\fR keyed output lines are:
.sp
.ne 2
.mk
.na
\fB\fBcmd\fR \fIcommand\fR\fR
.ad
.RS 19n
.rt  
\fIcommand\fR is a candidate for \fB--??keys\fR option string generation. This is triggered by \fBb_command(int argc\fR, in the input.
.RE

.sp
.ne 2
.mk
.na
\fB\fBdef\fR \fIname string\fR\fR
.ad
.RS 19n
.rt  
\fIname\fR is a candidate variable with \fIstring\fR value string.
.RE

.sp
.ne 2
.mk
.na
\fB\fBstr\fR \fIstring\fR\fR
.ad
.RS 19n
.rt  
\fIstring\fR should be entered into the catalog.
.RE

.sp
.ne 2
.mk
.na
\fB\fBvar\fR \fIname\fR\fR
.ad
.RS 19n
.rt  
If \fBdef\fR \fIname\fR occurs then its string value should be entered into the catalog.
.RE

.sp
.LP
The input source file is preprocessed with the \fBpp:allpossible\fR option on. This enables non-C semantics. All source should first be compiled error-free with a real compiler before running \fBmsgcpp\fR. The following changes are enabled for the top level files. Included file behavior is not affected.
.RS +4
.TP
1.
All \fB#if\fR, \fB#ifdef\fR and \fB#ifndef\fR branches are enabled.
.RE
.RS +4
.TP
2.
The first definition for a macro is retained, even when subsequent \fB#define\fR statements would normally redefine the macro. \fB#undef\fR must be used to redefine a macro.
.RE
.RS +4
.TP
3.
Macro calls with an improper number of arguments are silently ignored.
.RE
.RS +4
.TP
4.
\fB#include\fR on non-existent headers are silently ignored.
.RE
.RS +4
.TP
5.
Invalid C source characters are silently ignored.
.RE
.sp
.LP
\fBmsgcat.h\fR is included if it exists. This file may contain macro definitions for functions that translate string arguments. If \fBfoo\fR is a function that translates its string arguments then include the line \fB#define foo _TRANSLATE_\fR in \fBmsgcat.h\fR, or specify the option \fB-Dfoo=_TRANSLATE_\fR. If \fBbar\fR is a function that translates string arguments if the first argument is \fBstderr\fR, then use either \fB#define bar _STDIO_\fR or \fB-Dbar=_STDIO_\fR. 
.sp
.LP
The macro \fB_BLD_msgcat\fR is defined to be \fB1\fR. As an alternative to \fBmsgcat.h\fR, \fB_TRANSLATE_\fR definitions could be placed inside \fB#ifdef _BLD_msgcat ... #endif\fR. 
.SH OPTIONS
.sp
.LP
The following options are supported:
.sp
.ne 2
.mk
.na
\fB\fB-A\fR\fR
.ad
.br
.na
\fB\fB--assert=\fR\fIassertion\fR\fR
.ad
.RS 25n
.rt  
Enter the assertion using \fB#assert\fR for system V compatibility.
.RE

.sp
.ne 2
.mk
.na
\fB\fB-C\fR\fR
.ad
.br
.na
\fB\fB--comments\fR\fR
.ad
.RS 25n
.rt  
Pass comments to the output. 
.sp
Comments are omitted by default.
.RE

.sp
.ne 2
.mk
.na
\fB\fB-D\fR\fR
.ad
.br
.na
\fB\fB--define=\fR\fIname\fR\fB[=\fR\fIvalue\fR\fB]\fR\fR
.ad
.RS 25n
.rt  
Define the macro \fIname\fR to have \fIvalue\fR. This is the only portable way to pass options through \fBcc\fR to \fBcpp\fR(1). 
.RS +4
.TP
.ie t \(bu
.el o
If \fB=\fR\fIvalue\fR is omitted, \fIvalue\fR is assumed to be \fB1\fR .
.RE
.RS +4
.TP
.ie t \(bu
.el o
If \fIname\fR begins with \fB:\fR, then it is interpreted as a \fBlibpp\fR \fB#pragma pp\fR: statement.
.RE
.RS +4
.TP
.ie t \(bu
.el o
If \fIname\fR begins with \fB%\fR, it is interpreted as a \fBlibpp\fR \fB#\fR directive statement.
.RE
.RS +4
.TP
.ie t \(bu
.el o
If name begins with a \fB-\fR or a \fB+\fR, it is interpreted as a \fBlibpp\fR option.
.sp
\fB-\fR turns the option on, \fB+\fR turns it off.
.RE
.RS +4
.TP
.ie t \(bu
.el o
Most options have a \fB#pragma\fR counterpart that is listed with the option definition.
.RE
.sp
.ne 2
.mk
.na
\fB\fB-D-C\fR\fR
.ad
.br
.na
\fB\fBpp:compatibility\fR\fR
.ad
.sp .6
.RS 4n
Preprocess for K&R C compatibility.
.RE

.sp
.ne 2
.mk
.na
\fB\fB-D-D\fR\fIlevel\fR\fR
.ad
.br
.na
\fB\fBpp:debug level\fR \fIlevel\fR\fR
.ad
.sp .6
.RS 4n
Set the debug trace level. 
.sp
Specify \fIlevel\fR as a number greater than or equal to \fB0\fR. Higher levels produce more output. Levels higher than \fB3\fR can only be enabled in the \fB-g\fR compiled versions.
.RE

.sp
.ne 2
.mk
.na
\fB\fB-D-F\fR\fIname\fR\fR
.ad
.sp .6
.RS 4n
Set the main input file name to \fIname\fR. This only affects the error messages and the line sync output.
.RE

.sp
.ne 2
.mk
.na
\fB\fB-D-H\fR\fR
.ad
.br
.na
\fB\fBpp:hosted\fR\fR
.ad
.sp .6
.RS 4n
All directories are hosted. Compatibility warning messages from the hosted directory headers are suppressed.
.RE

.sp
.ne 2
.mk
.na
\fB\fB-D-I\fR\fR
.ad
.br
.na
\fB\fBpp:cdir\fR\fR
.ad
.sp .6
.RS 4n
All directories contain C headers. This option is only used only with \fB-D-+\fR.
.RE

.sp
.ne 2
.mk
.na
\fB\fB-D-K\fR\fR
.ad
.br
.na
\fB\fBpp:keyargs\fR\fR
.ad
.sp .6
.RS 4n
Enable the non-standard \fIname\fR\fB=\fR\fIvalue\fR macro argument mode.
.RE

.sp
.ne 2
.mk
.na
\fB\fB-D-L\fR\fB[\fR\fIid\fR\fB]\fR\fR
.ad
.br
.na
\fB\fBpp:lineid [\fR\fIid\fR]\fR
.ad
.sp .6
.RS 4n
Set the line sync directive id to \fIid\fR. If \fIid\fR is not specified, set to null.
.RE

.sp
.ne 2
.mk
.na
\fB\fB-D-M\fR\fR
.ad
.br
.na
\fB\fBpp:nomultiple\fR\fR
.ad
.sp .6
.RS 4n
Disable multiple include detection.
.RE

.sp
.ne 2
.mk
.na
\fB\fB-D-P\fR\fR
.ad
.br
.na
\fB\fBpp:passthrough\fR\fR
.ad
.sp .6
.RS 4n
Enable the non-standard passthrough mode. This can be useful for processing non-C input.
.RE

.sp
.ne 2
.mk
.na
\fB\fB-D-Q\fR\fR
.ad
.br
.na
\fB\fBpp:dump\fR\fR
.ad
.sp .6
.RS 4n
Dump macro definitions to the output so that the output may be passed through \fBcpp\fR again. This is used for generating precompiled headers.
.RE

.sp
.ne 2
.mk
.na
\fB\fB-D-R\fR\fR
.ad
.br
.na
\fB\fBpp:transition\fR\fR
.ad
.sp .6
.RS 4n
Enable the transition preprocessing mode. This is used for compilers that cannot make up their semantics between K&R and ISO C.
.RE

.sp
.ne 2
.mk
.na
\fB\fB-D-S\fR\fR
.ad
.br
.na
\fB\fBpp:strict\fR\fR
.ad
.sp .6
.RS 4n
Enable strict preprocessing semantics and warnings. This works with any mode (compatibility, transition, or the default ISO).
.RE

.sp
.ne 2
.mk
.na
\fB\fB-D-T\fR\fItest\fR\fR
.ad
.br
.na
\fB\fBpp:test\fR \fItest\fR\fR
.ad
.sp .6
.RS 4n
Enable implementation specific test code according to \fItest\fR.
.RE

.sp
.ne 2
.mk
.na
\fB\fB-D-W\fR\fR
.ad
.br
.na
\fB\fBpp:warn\fR\fR
.ad
.sp .6
.RS 4n
Enable pedantic warnings in non-hosted files.
.RE

.sp
.ne 2
.mk
.na
\fB\fB-D-X\fR\fB[cc]\fR\fR
.ad
.br
.na
\fB\fB\fR\fR
.ad
.sp .6
.RS 4n
Preprocess for the \fBcc\fR compiler, which must be an executable path or an executable on \fB$PATH\fR.
.RE

.sp
.ne 2
.mk
.na
\fB\fB-D-Z\fR\fR
.ad
.br
.na
\fB\fBpp:pool\fR\fR
.ad
.sp .6
.RS 4n
Enable pool mode.
.RE

.sp
.ne 2
.mk
.na
\fB\fB-D-d\fR\fR
.ad
.sp .6
.RS 4n
List canonicalized \fB#define\fR statements for non-predefined macros in the output.
.RE

.sp
.ne 2
.mk
.na
\fB\fB-D-m\fR\fR
.ad
.sp .6
.RS 4n
List canonicalized \fB#define\fR statements for all macros. All other output is disabled.
.RE

.sp
.ne 2
.mk
.na
\fB\fB-D-+\fR\fR
.ad
.br
.na
\fB\fBpp:plusplus\fR\fR
.ad
.sp .6
.RS 4n
Preprocess for the C++ dialect.
.RE

.RE

.sp
.ne 2
.mk
.na
\fB\fB-E\fR\fR
.ad
.br
.na
\fB\fB--preprocess\fR\fR
.ad
.RS 25n
.rt  
Ignored; for compatibility with very old compilers.
.RE

.sp
.ne 2
.mk
.na
\fB\fB-H\fR\fR
.ad
.br
.na
\fB\fB--include-reference\fR\fR
.ad
.RS 25n
.rt  
Emit \fB#include\fR file paths on the standard error, one per line, indented to show nesting.
.RE

.sp
.ne 2
.mk
.na
\fB\fB-I\fR\fR
.ad
.br
.na
\fB\fB--include[=\fR\fIdirectory\fR\fB]\fR\fR
.ad
.RS 25n
.rt  
Append directory to the list of directories searched for \fB#include\fR files. 
.sp
If directory is \fB-\fR: 
.RS +4
.TP
1.
\fB-I\fR directories before \fB-I-\fR are searched only for \fB"..."\fR include files
.RE
.RS +4
.TP
2.
\fB-I\fR directories after \fB-I-\fR are searched for \fB"..."\fR and \fB<"...">\fR include files
.RE
.RS +4
.TP
3.
the directory \fB\&.\fR is searched only if it is explicitly specified by an \fB-I\fR option
.RE
.sp
.ne 2
.mk
.na
\fB\fB-I-C\fR\fIdirectory\fR\fR
.ad
.br
.na
\fB\fBpp:cdir directory\fR\fR
.ad
.sp .6
.RS 4n
Mark \fIdirectory\fR as a C header directory. This option is used with \fBpp:plusplus\fR.
.RE

.sp
.ne 2
.mk
.na
\fB\fB-I-D[\fR\fIfile\fR]\fR
.ad
.sp .6
.RS 4n
Read the default \fBprobe\fR definitions from \fIfile\fR, or ignore the default definitions if \fIfile\fR is omitted.
.RE

.sp
.ne 2
.mk
.na
\fB\fB-I-H\fR\fIdirectory\fR\fR
.ad
.br
.na
\fB\fBpp:hostdir\fR \fIdirectory\fR\fR
.ad
.sp .6
.RS 4n
Mark directory as a hosted directory. Headers from hosted directories have compatibility warnings disabled.
.RE

.sp
.ne 2
.mk
.na
\fB\fB-I-I\fR\fIheader\fR\fR
.ad
.br
.na
\fB\fBpp:ignore\fR \fIheader\fR\fR
.ad
.sp .6
.RS 4n
Add \fIheader\fR to the list of ignored headers.
.RE

.sp
.ne 2
.mk
.na
\fB\fB-I-M\fR\fIfile\fR\fR
.ad
.sp .6
.RS 4n
\fIfile\fR contains a sequence of header \fB[= "map" ]\fR lines, where header is either \fB<name>\fR or \fB"name"\fR, and \fB"map"\fR is an explicit binding for header. header is ignored \fBif = "map"\fR is omitted.
.RE

.sp
.ne 2
.mk
.na
\fB\fB-I-R\fR\fIfile\fR\fR
.ad
.sp .6
.RS 4n
Include \fIfile\fR but do not emit text or line syncs.
.RE

.sp
.ne 2
.mk
.na
\fB\fB-I-S\fR\fIdirectory\fR\fR
.ad
.sp .6
.RS 4n
Add \fIdirectory\fR to the default standard include directory list.
.RE

.sp
.ne 2
.mk
.na
\fB\fB-I-T\fR\fIfile\fR\fR
.ad
.sp .6
.RS 4n
Include \fIfile\fR and emit text to the output file. The option value can be omitted.
.RE

.RE

.sp
.ne 2
.mk
.na
\fB\fB-M\fR\fR
.ad
.br
.na
\fB\fB--dependencies\fR\fR
.ad
.RS 25n
.rt  
Generate \fBmake\fR(1S) dependencies. This option is not needed with \fBnmake\fR. 
.sp
The \fB-M\fR option can be followed by optional flags to change the dependency output styles. 
.sp
The following optional flags are supported:
.sp
.ne 2
.mk
.na
\fB\fBD\fR\fR
.ad
.RS 5n
.rt  
Generate dependencies in a separate \fB\&.d\fR file. Preprocessed output is still written to output, or the standard output if output is omitted.
.RE

.sp
.ne 2
.mk
.na
\fB\fBG\fR\fR
.ad
.RS 5n
.rt  
Also generate missing dependencies.
.RE

.sp
.ne 2
.mk
.na
\fB\fBM\fR\fR
.ad
.RS 5n
.rt  
Only generate local header dependencies. Hosted headers are omitted. Hosted headers are determined by the \fB-I-H\fR option and the -\fB-pp:hosted\fR and \fBpp:hostdir pragmas\fR. No special distinction is made between the \fB""\fR and \fB<>\fR include styles.
.RE

.RE

.sp
.ne 2
.mk
.na
\fB\fB-P\fR\fR
.ad
.br
.na
\fB\fB--sync\fR\fR
.ad
.RS 25n
.rt  
Emit line syncs.
.sp
Line sync is turned on by default. \fB-P\fR means \fB--nosync\fR.
.RE

.sp
.ne 2
.mk
.na
\fB\fB-T\fR\fB[\fR\fIlength\fR\fB]\fR\fR
.ad
.RS 25n
.rt  
If not \fBgcc\fR, truncate identifiers to \fIlength\fR characters for compatibility with old AT&T compilers.
.RE

.sp
.ne 2
.mk
.na
\fB\fB-U\fR\fR
.ad
.br
.na
\fB\fB--undefine=\fR\fIname\fR\fR
.ad
.RS 25n
.rt  
Remove the definition for the macro \fIname\fR.
.RE

.sp
.ne 2
.mk
.na
\fB\fB-V\fR\fR
.ad
.br
.na
\fB\fB--version\fR\fR
.ad
.RS 25n
.rt  
Emit the \fBlibpp\fR version.
.RE

.sp
.ne 2
.mk
.na
\fB\fB-X\fR\fR
.ad
.br
.na
\fB\fB--argmode\fR\fR
.ad
.RS 25n
.rt  
Enable \fIname\fR\fB=\fR\fIvalue\fR macro arguments for \fBeasel\fR compatibility.
.RE

.sp
.ne 2
.mk
.na
\fB\fB-Y\fR\fR
.ad
.br
.na
\fB\fB--standard=\fR\fIdirectory\fR\fR
.ad
.RS 25n
.rt  
Add \fIdirectory\fR to the list searched for \fB#include <...>\fR files.
.RE

.SH OPERANDS
.sp
.LP
The following operands are supported:
.sp
.ne 2
.mk
.na
\fB\fIinput\fR\fR
.ad
.RS 10n
.rt  
Specifies C source file to preprocess.
.RE

.sp
.ne 2
.mk
.na
\fB\fIoutput\fR\fR
.ad
.RS 10n
.rt  
Specifies output file.
.RE

.SH EXIT STATUS
.sp
.ne 2
.mk
.na
\fB\fB0\fR\fR
.ad
.RS 6n
.rt  
Successful completion.
.RE

.sp
.ne 2
.mk
.na
\fB\fB>0\fR\fR
.ad
.RS 6n
.rt  
An error occurred.
.RE

.SH EXAMPLES
.LP
\fBExample 1 \fRUsing \fBmsgcpp\fR to Extract Localizable Strings
.sp
.LP
The following example uses \fBmsgcpp\fR to extract localizable strings from the file \fBhello.c\fR, marked using the \fBERROR_dictionary()\fR, and writes them to the file \fBhello.mso\fR: 

.sp
.in +2
.nf
example% cat hello.c


#include <stdio.h>
#include <stdlib.h>

/*
 * dummy macro to avoid including
 * libast headers
 */
#define ERROR_dictionary(x) x

int main(int ac, char *av[])
{
    puts( ERROR_dictionary("hello world") );
    puts( ERROR_dictionary("hello all") );
    return( EXIT_SUCCESS );
 }

example% msgcpp -D__STDC__ -D__i386 hello.c hello.mso

example% cat hello.mso
str "hello world"
str "hello all"
.fi
.in -2
.sp

.SH AUTHORS
.sp
.LP
Glenn Fowler, \fBgsf@research.att.com\fR
.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp

.sp
.TS
tab() box;
cw(2.75i) |cw(2.75i) 
lw(2.75i) |lw(2.75i) 
.
ATTRIBUTE TYPEATTRIBUTE VALUE
_
Availabilitydeveloper/astdev
_
Interface StabilityVolatile 
.TE

.SH SEE ALSO
.sp
.LP
\fBcpp\fR(1), \fBgencat\fR(1), \fBmsgcc\fR(1), \fBmsgcvt\fR(1), \fBmsggen\fR(1), \fBmake\fR(1S), \fBattributes\fR(5)
.sp
.LP
Kernighan, Brian W. and Ritchie, Dennis M., \fIThe C Programming Language\fR, Prentice Hall, 1988.
